package cn.com.anypay.manager.payment.core;

import cn.com.anypay.manager.payment.dto.PaymentRequestDTO;
import cn.com.anypay.manager.payment.dto.PaymentResultDTO;
import cn.com.anypay.manager.payment.dto.QueryRequestDTO;
import cn.com.anypay.manager.payment.dto.QueryResultDTO;

/**
 * 支付渠道核心接口
 *
 * 定义所有支付渠道必须实现的标准操作，遵循开闭原则，
 * 支持渠道的插件化扩展
 *
 * @author AnyPay Team
 * @version 1.0
 * @since 2025-07-05
 */
public interface IPaymentChannel {

    /**
     * 获取渠道唯一标识
     *
     * @return 渠道标识，如 "wxpay", "alipay", "channeltest1"
     */
    String getChannelId();

    /**
     * 获取渠道名称
     *
     * @return 渠道显示名称
     */
    String getChannelName();

    /**
     * 获取渠道版本
     *
     * @return 渠道版本号
     */
    String getVersion();

    /**
     * 检查渠道是否可用
     *
     * @return true 如果渠道可用，false 否则
     */
    boolean isAvailable();

    /**
     * 初始化渠道
     *
     * @throws PaymentException 初始化失败时抛出
     */
    void initialize() throws PaymentException;

    /**
     * 销毁渠道资源
     */
    void destroy();

    /**
     * 创建支付订单
     *
     * @param request 支付请求
     * @return 支付结果，包含支付链接、二维码等信息
     * @throws PaymentException 支付创建失败时抛出
     */
    PaymentResultDTO createPayment(PaymentRequestDTO request) throws PaymentException;

    /**
     * 查询支付状态
     *
     * @param request 查询请求
     * @return 查询结果，包含支付状态等信息
     * @throws PaymentException 查询失败时抛出
     */
    QueryResultDTO queryPayment(QueryRequestDTO request) throws PaymentException;

    /**
     * 关闭支付订单
     *
     * @param orderId 订单ID
     * @return 操作结果
     * @throws PaymentException 关闭失败时抛出
     */
    boolean closePayment(String orderId) throws PaymentException;

    /**
     * 验证回调签名
     *
     * @param data 回调数据
     * @return true 如果签名验证通过，false 否则
     * @throws PaymentException 验证过程中发生异常时抛出
     */
    boolean verifyCallback(String data) throws PaymentException;

    /**
     * 处理支付回调
     *
     * @param data 回调数据
     * @return 处理结果
     * @throws PaymentException 处理失败时抛出
     */
    PaymentResultDTO processCallback(String data) throws PaymentException;

    /**
     * 获取支持的支付产品
     *
     * @return 支付产品列表，如 ["JSAPI", "NATIVE", "APP", "H5"]
     */
    String[] getSupportedPayProducts();

    /**
     * 获取渠道配置模板
     *
     * @return 配置模板，用于生成配置表单
     */
    String getConfigTemplate();

    /**
     * 验证渠道配置
     *
     * @param config 配置字符串
     * @return 验证结果
     */
    boolean validateConfig(String config);

    /**
     * 注册渠道支持的支付产品
     *
     * @param productFactory 产品工厂
     */
    void registerProducts(cn.com.anypay.manager.payment.factory.PaymentProductFactory productFactory);
}